\documentclass[a4paper,12pt]{article} 
\begin{document} 
\sloppy
\tableofcontents

\section{Introduction}
\subsection{What's it?}
``selftree.inc'' is an include-file-generator that is written in the
POVRay-scripting-language. The generated includes contain one or more
objects, which may looks like trees, if the parameters are set neatly.

Shape, looking and complexity of the objects ineracting with a big
bunch of parameters.

It is not needed to read following guide completely. For usage only
it's enough to read the sections about usage and the one about the
variables, leafs and textures. The rest is idle talk.

Ah, and sorry for my poor english...

\subsection{Why?}
The idea to write a tree-include is from a student of mathematics
(hello, Holger!). But his includes contained no recursion. If you
want ten nesting, you have to take ten includes... After long
discussions, how to solve this problem he gave me the definitively
proof, that there is no way to make recursive includes in
POVRay. Nevertheless I decided to find a way. ``selftree.inc'' is the
way.

\section{Usage}
\subsection{General}
To use the object generated by ``selftree.inc'', we need a little
trick. The include writes the source of the generated object to the
\#debug-stream. To use the objects in your scenen-file, the
\#debug-stream must be written to another file. This can be done with
the POVRay commandline-parameter -GD\_FILENAME\_ (or -GD\_FILENAME\_,
if you want to see the output from ``selftree.inc''. You don't need to
see it, it's not very interesting. If you want some infos, some
statistics are written to the \#statitics-stream after parsing the
objects.). This commandline-parameter sends the \#debug-stream to the
file \_FILENAME\_. This file must included {\bf after}
``selftree.inc'' in your scene-file. Before all this you should set a
bunch of variables to influence the shape and the complexity of the
trees (although the defaults generate usable trees).

So the following steps are needed to generate a tree:
\begin{itemize}
\item{Set a big bunch of variables (or be satisfied with the
default-tree).} 
\item{Include ``selftree.inc'' in your scene-file.}
\item{Eventually repeat the first two steps to generate multiple trees.}
\item{Include \_FILENAME\_ in your scene-file, where \_FILENAME\_ is
the name of the by -GD\_FILENAME\_ generated file.}
\item{Insert an object-statement with thegenerated tree-object:\\
object \{ TREE texture \{...\} rotate \{...\} translate \{...\}\}}
\item{Run POVRay like this:\\
{\bf povray +Imyscene.pov -GD\_FILENAME\_}... more POVRay-arguments}
\end{itemize}

\subsection{Variables}
``selftree.inc'' can be modified by a big bunch of variables. There
are three types of variables:
\begin{itemize}
\item{Simple numbers: There are only two of them: DEPTH and NRLEAFINCS.}
\item{Strings: They must be set in parentheses and should contain a
simple string, preferably without spaces or special
characters. Example:\\ 
{\bf \#declare OBJECTNAME = ``mytree''}}
\item{Functions: Most of the variables are functions, which are
calculated in dependance of the current recursion-step. Functions can
have constant values ({\bf \#declare NRBRANCHES = ``3''}) oder they
can be defined as functions in dependance of X (capital X): ({\bf
\#declare NRBRANCHES = ``int(sqrt(X)+(X/2))''}). The advantage of this
is the possibility to influence the tree more accurately. For example
with a simple function the tree can branch out more at the top than at
the bottom of the recursion.}
\end{itemize}

Aside from DEPTH, NRLEAFINCS and the texture-modifiers all variables
should be defined in parentheses. 

``selftree.inc'' does not check the variables. It is presumed (this is
the major bug in this include...) that nobody ever makes a
mistake. However, if someone makes a mistake, it is presumed, that he
he will notice...

The values of many of the variables are inluenced by random-functions
when the trees are generated (Setting only the seed-value of a
random-generator to another value can change the tree enormous). A
little luck and experience help to find good values.

The following is a description of all variables, their defaults and
some hints for good values (for a short reference look at the
include-file itself).

\subsubsection{OBJECTNAME}
\begin{enumerate}
\item{Description:} To distinguish between different trees, they must
have names. With this variable you set the name of the next tree. 
\item{Default:} ``TREE'' (String)
\item{Note:} If you generate multiple trees without setting OBJECTNAME
 every time to a new name, the previous trees are overwritten.
\end{enumerate}

\subsubsection{USESTDTRUNK}
\begin{enumerate}
\item{Description:} The parts of the trees are made of cones and
spheres. To make the trees more realistic, you can define your own
shape for the trunk. This variable is a bool, that says, if the
default-trunk should be used or not.
\item{Default:} ``YES''
\end{enumerate}

\subsubsection{TRUNKLEN}
\begin{enumerate}
\item{Description:} How long should the trunk be? This value is for
both the default-trunk and the user-defined one.
\item{Default:} ``5''
\end{enumerate}

\subsubsection{TRUNKBASER}
\begin{enumerate}
\item{Description:} What radius should the trunk have at his base?
\item{Default:} ``0.7''
\end{enumerate}

\subsubsection{TRUNKCAPR}
\begin{enumerate}
\item{Description:} What radius should the trunk have at his top?
\item{Default:} ``0.5''
\end{enumerate}

\subsubsection{DEPTH}
\begin{enumerate}
\item{Description:} This is the recursion-depth for the trees, which
means how often the tree branches from the trunk to the branchtops.
\item{Default:} 6
\item{Note:} This one must not set in parentheses.
\end{enumerate}

\subsubsection{BLEN}
\begin{enumerate}
\item{Description:} How long the branches should be at the first
recursion-step (the branches the trunk).
\item{Default:} ``5''
\item{Note:} We only have to define this length, because the branches
in the deeper recursion-steps are scaled and a little bit varied
versions of these.
\end{enumerate}

\subsubsection{LDIFF}
\begin{enumerate}
\item{Description:} The range for random variations of the
branch-legth. 
\item{Default:} ``0''
\item{Note:} This value is added to BLEN and is scaled in deeper
recursion-steps also.
\end{enumerate}

\subsubsection{RADIUS}
\begin{enumerate}
\item{Description:} The radius of the branches at the first
recursion-step.
\item{Default:} ``0.5''
\item{Note:} To have a smooth transit you should set this to the same
value as TRUNKCAPR.
\end{enumerate}

\subsubsection{RADSCALE}
\begin{enumerate}
\item{Description:} The scale for the branch-radius.
\item{Default:} ``0.5''
\end{enumerate}

\subsubsection{RDIFF}
\begin{enumerate}
\item{Description:} The range for random variations of RADIUS.
\item{Default:} ``0''
\item{Note:} Would be subtracted from RADIUS and is scaled in deeper
recursion-steps also.
\end{enumerate}

\subsubsection{RECSCALE}
\begin{enumerate}
\item{Description:} The general scale-value for the recursion.
\item{Default:} ``0.5''
\item{Note:} This is valid for all values, which have no own
scale-value. 
\end{enumerate}

\subsubsection{SLOPEANGLE}
\begin{enumerate}
\item{Description:} The slope-angle for the branches.
\item{Default:} ``40''
\end{enumerate}

\subsubsection{SANGLEDIFF}
\begin{enumerate}
\item{Description:} The range for random variations of SLOPEANGLE.
\item{Default:} ``0''
\item{Note:} Would be added to SLOPEANGLE.
\end{enumerate}

\subsubsection{ANGLESCALE}
\begin{enumerate}
\item{Description:} The scale for SLOPEANGLE.
\item{Default:} ``1.1''
\end{enumerate}

\subsubsection{NRBRANCHES}
\begin{enumerate}
\item{Description:} The number of child-branches a branch or the trunk
can have.
\item{Default:} ``4''
\item{Note:} Here you can write some little funktions which make very
good trees. (attention: you should keep in mind that the values of the
function do not grow to big, the number of objects which build the
tree can grow very fast to very gigantic values.)
\end{enumerate}

\subsubsection{NRBDIFF}
\begin{enumerate}
\item{Description:} The range for random variations of NRBRANCHES.
\item{Default:} ``0''
\item{Note:} Would be added to NRBRANCHES.
\end{enumerate}

\subsubsection{NRBSCALEADD}
\begin{enumerate}
\item{Description:} One of two scales for NRBRANCHES.
\item{Default:} ``0''
\item{Note:} This variable is a relict from old versions which did not
understand functions. These values can better simpulated by functions
in NRBRANCHES. But if you don't want to write functions, these two
values are good alternatives. 

The value would be added to NRBRANCHES in every recursion-step.
\end{enumerate}

\subsubsection{NRBSCALEMUL}
\begin{enumerate}
\item{Description:} The second scale for NRBRANCHES.
\item{Default:} ``1''in every recursion-step.
\item{Note:} NRBRANCHES would be multiplied with NRBSCALEMUL in every
 recursion-step. 
\end{enumerate}

\subsubsection{BRANCHTOP}
\begin{enumerate}
\item{Description:} A threshold for the probability that a branch is
put to the top of his predecessor.
\item{Default:} ``0.6''
\item{Note:} If a random-value between 0 and 1 is bigger than
BRANCHTOP, then the branch is put to a random place at his
predecessor, otherwise it is put at the top.
\end{enumerate}

\subsubsection{LEAFINC}
\begin{enumerate}
\item{Description:} Shoult the tree have leafs?
\item{Default:} ``NO''
\end{enumerate}

\subsubsection{NRLEAFINCS}
\begin{enumerate}
\item{Description:} How many different leaf-shapes are defined?
\item{Default:} 0
\item{Note:} This one must not set in parentheses.

For a description how to define leafs see chapter 3 about leafs.
\end{enumerate}

\subsubsection{NRLEAFS}
\begin{enumerate}
\item{Description:} How many leafs should a branch have?
\item{Default:} ``0''
\item{Note:} Only the topmost branches have leafs.
\end{enumerate}

\subsubsection{NRLDIFF}
\begin{enumerate}
\item{Description:} The range for random variations of NRLEAFS
\item{Default:} ``0''
\item{Note:} Would be added to NRLEAFS.
\end{enumerate}

\subsubsection{ROTRANGE}
\begin{enumerate}
\item{Description:} The range of rotation for the branches around
their predecessors.
\item{Default:} ``360''
\item{Note:} With a little experience you can simulate phenomena like
wind with shrinking this value.
\end{enumerate}

\subsubsection{RANDINIT\_ROT}
\begin{enumerate}
\item{Description:} Seed for the random-generator for ROTRANGE.
\item{Default:} ``1.1234''
\item{Note:} The changing of one of these values can change the shape
of a tree dramatically. So if a tree has good structure but a bad
shape, you can improve (or worsen) the shape with changing one of the
seed-values. 
\end{enumerate}

\subsubsection{RANDINIT\_LDIFF}
\begin{enumerate}
\item{Description:} Seed for the random-generator for LDIFF.
\item{Default:} ``0.1234''
\end{enumerate}

\subsubsection{RANDINIT\_RDIFF}
\begin{enumerate}
\item{Description:} Seed for the random-generator for RDIFF.
\item{Default:} ``0.1234''
\end{enumerate}

\subsubsection{RANDINIT\_SDIFF}
\begin{enumerate}
\item{Description:} Seed for the random-generator for SANGLEDIFF.
\item{Default:} ``0.1234''
\end{enumerate}

\subsubsection{RANDINIT\_NRBDIFF}
\begin{enumerate}
\item{Description:} Seed for the random-generator for NRBDIFF.
\item{Default:} ``0.1234''
\end{enumerate}

\subsubsection{RANDINIT\_NRLDIFF}
\begin{enumerate}
\item{Description:} Seed for the random-generator for NRLDIFF.
\item{Default:} ``0.1234''
\end{enumerate}

\subsubsection{RANDINIT\_LEAFSELECT}
\begin{enumerate}
\item{Description:} Seed for the random-generator for the
random-choosing of the leafs.
\item{Default:} ``0.1234''
\end{enumerate}

\subsubsection{RANDINIT\_LEAFTRANS}
\begin{enumerate}
\item{Description:} Seed for the random-generator for the placing of
the leafs at the branches.
\item{Default:} ``0.1234''
\end{enumerate}

\subsubsection{RANDINIT\_LEAFROT}
\begin{enumerate}
\item{Description:} Seed for the random-generator for rotation of the
leafs. 
\item{Default:} ``0.1234''
\end{enumerate}

\subsubsection{RANDINIT\_BT}
\begin{enumerate}
\item{Description:} Seed for the random-generator for the treshold for
BRANCHTOP. 
\item{Default:} ``0.1234''
\end{enumerate}

\subsubsection{MOD\_TR}
\begin{enumerate}
\item{Description:} Texture for the trunk.
\item{Default:} the \#default-Textur is used.
\item{Note:} You should define a full texture, not only a
pigment-statement. Example:
\begin{verbatim}
texture {
   pigment {
      color DarkBrown
   }
   normal {
      bozo 0.2 
      scale <0.05, 0.2, 0.08>
   }
}
\end{verbatim}
\end{enumerate}

\subsubsection{MOD\_X}
\begin{enumerate}
\item{Description:} The textures for the branches in the different
recursion-steps. 
\item{Default:} the \#default-Textur is used.
\item{Note:} The X in the name is a place-holder. X is a number
between 0 and DEPTH-1 (0 means the branches at the trunk, DEPTH-1
means the topmost branches). This makes it possible to define a
texture the branches of every recursion-step individually (for example
it makes sense to define a smother texture for the small topmost
branches as for the thick branches at the trunk).
\end{enumerate}

\subsubsection{\#default}
\begin{enumerate}
\item{Description:} A default-texture for the tree.
\item{Default:} \{ pigment \{ color rgb $<0.35, 0.16, 0.14>$ \} \}
\item{Note:} If you have defined your own default-texture, you should
save it and restore it afer using ``selftree.inc''.
\end{enumerate}

\section{Leafs}
To generate not only wintery trees, ``selftree.inc'' can add leafs to
the trees, of course. To do thie, you must define
leafs. ``selftree.inc'' can have different leaf-shapes at one
tree. How many different shapes a tree has, is defined in NRLEAFINCS.

The names of the leaf-objects must be set as follows: LEAFINC\_X where
X is a number between 0 and NRLEAFINCS-1. Is the value of NRLEAFINCS
11, then ``selftree.inc'' looks for leafs with the names LEAFINC\_0,
LEAFINC\_1, ..., LEAFINC\_10.

It is presumed, that the shaft of the leaf starts at $<0,0,0>$ and the
direction of the leaf is Y.

This is an example for a leaf-definition:
\begin{verbatim}
#declare LEAFINC_0 =
sphere
{
  <0, 0, 0>, 0.3
  scale <1, 0.1, 0.5>
  translate <0.3, 0, 0>
  pigment { color Green }
}
\end{verbatim}

\subsection{leafshapes.inc}
This include defines a little number of leafs. If you render the file
leafs.pov, you can see all the different leafs.

\section{How does it work?}
To get real recursion in POVRay, we have to take a little trick:
POVRay string-functions are powerful enough to build
POVRay-statements. So we build the needed statements and write them to
the \#debug-stream (or another stream, which is not used by POVRay
itself). Then we send this stream to a file (with -GD\_FILENAME\_, if
you use the \#debug-stream) and include this file in our scene-file.

To get recursion, you only have to generate source-code with nested
while-statements. That's all...

If you want to have a variable recursion-depth, you can use two
while-statements: one for opening all recursion-steps, the other for
closing them.

\section{General stuff}
\subsection{History}
\begin{enumerate}
\item{Version 1.0:}
This is the firs finished release of the include. Previous versions
though are released, but had no good docs and horribly formatted
source-code. There may be incompatibilities to the older versions.
\end{enumerate}

\subsection{Todo}
\begin{enumerate}
\item{User-defined objects for the branch-shapes, for more realistic
and interesting branches.}
\item{A ``translation-tracker'', to align branches and leafs to
defined directions (for simulating gravity, wind etc.)}
\item{Nicer output with correct indention.}
\item{``Joker-variables'' for choosing different classes of trees (for
beginners, which don't want to set all the variables): small and many
branches, slim and high or oak-like, pine-like --- but that's very
utopian.}
\item{Better and enhanced leafshapes.inc}
\item{A number of bark-textures in bark.inc}
\item{Generating other plants by setting a plant-class (at this time
you can make a cactus with setting the variables to very strange
values...)}
\item{Checking the variable-values.}
\item{Restore the default-texture.}
\end{enumerate}

\subsection{Bugs}
Surely there are some, but I haven't them yet. If you find some or
have questions and suggestions, mail me:

stk@informatik.uni-bremen.de\\
(http://www.informatik.uni-bremen.de/~$\tilde{}$~stk)

\subsection{Thanksgiving}
Thanks for motivation and idea to the members of my little
POVRay-playgroup Holger Bettag
(http://www.informatik.uni-bremen.de/~$\tilde{}$~hobold) and Harald
Wagener (http://www.informatik.uni-bremen.de/~$\tilde{}$~hollow). 

\subsection{Copyright}
Although POVRay come not out of the GNU-corner, this file is under
GNU-copyright. Read the file COPYRIGHT for this.
\end{document}
